home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #2 / Monster Media No. 2 (Monster Media)(1994).ISO / prog_pas / ddplus63.zip / DOORDRIV.DOC < prev    next >
Text File  |  1993-01-03  |  44KB  |  1,327 lines
  1.           DoorDriver Door Kit                      By Scott M. Baker
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                      DoorDriver 5.00 - By Scott M. Baker
  9.  
  10.           Introduction - What is DoorDriver?
  11.           ----------------------------------
  12.               Doordriver is a set of .TPU units designed to be used
  13.           to create "Door" programs in the Turbo Pascal programming
  14.           language. The idea behind DoorDriver is that you
  15.           concentrate on writing your game and let DoorDriver do all
  16.           of the nasty ugly low-level details such as handling
  17.           serial I/O and processing BBS drop files.
  18.               Here are a listing of some of DoorDriver's finer
  19.           features:
  20.  
  21.               * Handles all serial I/O for you. You don't need to
  22.                 know a COM-PORT from a BAUD-RATE - DoorDriver'll do
  23.                 it for you.
  24.  
  25.               * Processes drop file from a variety of bbs systems -
  26.                 RBBS-PC, Wildcat, Spitfire, PC-Board, WWIV,
  27.                 Quickbbs, etc.
  28.  
  29.           Drop Files
  30.           ----------
  31.               Drop Files are the files created by the bulletin board
  32.           software when it goes to run a door. Obviously, the door
  33.           needs to know the user's name, baud rate, com port, etc,
  34.           right? Well, this is where that information goes. The BBS
  35.           creates a "Drop File" containing most information that the
  36.           door needs to operate.
  37.               These drop files vary from BBS software to BBS
  38.           software, although some standards are emerging. For this
  39.           purpose, DoorDriver includes support for several different
  40.           drop file formats.
  41.  
  42.           Overview of Routines
  43.           --------------------
  44.               The procedures, functions, and variables in DoorDriver
  45.           can be categorized into several different groups:
  46.  
  47.               * INPUT [INP]
  48.  
  49.                         Get information from the user who is online.
  50.                         Example: SREAD() which performs the
  51.                         functional equivelant of READLN().
  52.  
  53.               * OUTPUT [OUT]
  54.  
  55.                         Send information to the user. Example:
  56.                         SWRITE() which performs the equivelant of
  57.                         WRITE().
  58.  
  59.               * INFORMATIONAL [INF]
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.           DoorDriver Door Kit                      By Scott M. Baker
  68.  
  69.  
  70.  
  71.  
  72.  
  73.                         Provide information about the user, such as
  74.                         his name, baud rate, etc. Example:
  75.                         USER_FIRST_NAME which stores the current
  76.                         user's first name.
  77.  
  78.                         Informational variables are usually
  79.                         read-only, but some can be written to as
  80.                         well. Use common sense and you should get
  81.                         by.
  82.  
  83.               * CONTROL [CTL]
  84.  
  85.                         Procedures which perform various control
  86.                         functions over how doordriver operates.
  87.  
  88.               In the reference sections of this manual, all
  89.           functions/procedures/etc will be placed in one of these
  90.           categories for your convenience.
  91.  
  92.           (copy "converting your program into a door")
  93.  
  94.           Configuration - The Control File
  95.           --------------------------------
  96.               For the convenience of both the author and the sysops
  97.           who will be running the door, DoorDriver picks up some of
  98.           it's configuration data from a "control file". A control
  99.           file is a plain ASCII file which contains special commands
  100.           and directives to tell DoorDriver how to behave. For
  101.           example, this includes which BBS drop files to use, the
  102.           Sysop's name, etc.
  103.               A Sample control file (DOORDRIV.CTL) is included. You
  104.           may designate any name you wish as the name of the control
  105.           file for your door (for example, my CDRDOOR program uses
  106.           CDRDOOR.CTL; News door uses NEWS.CTL, etc)
  107.               The control file is loaded and processed automatically
  108.           when your program calls "INITDOORDRIVER". (This will be
  109.           described further down).
  110.  
  111.           Command Line Parameters
  112.           -----------------------
  113.               DoorDriver supports several parameters which may be
  114.           specified on the command line. These parameters are
  115.           automatically processed for you when you call
  116.           "INITDOORDRIVER".
  117.  
  118.               "/L"      This tells DoorDriver to load up in LOCAL
  119.           mode. This is good for testing or when a sysop just wants
  120.           to "try out" the door without messing with his BBS setup.
  121.           The "/L" mode will ask the user for his name and run the
  122.           door in local mode.
  123.  
  124.               "/S"      This command will tell doordriver to load up
  125.           in the Sysop FAST local mode. The only difference between
  126.           this and "/L" above is that the sysop is not asked his
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.           DoorDriver Door Kit                      By Scott M. Baker
  134.  
  135.  
  136.  
  137.  
  138.  
  139.           name - it is plucked out of the control file
  140.           automatically.
  141.  
  142.               "/M"      This is a generic maintenance mode. It logs
  143.           into the game with the name "SYSTEM MAINT" in local mode.
  144.           You can use it if your program requires a nightly
  145.           maintenance or something similar.
  146.  
  147.               "/Nx"     (where x is 1..9) This specifies a "node
  148.           number". Some bbs software support multinode environments
  149.           in which you must know the node number of the drop file to
  150.           use. For example, RBBS-PC uses DORINFOx.DEF. If you
  151.           specified "/N2" then doordriver would use DORINFO2.DEF.
  152.  
  153.               "/Pyyy"   This specifies the PATH to the drop files.
  154.           For example, "/PC:\BBS" would tell DoorDriver to look for
  155.           the drop files in C:\BBS.
  156.  
  157.           Reference - Procedures
  158.           ----------------------
  159.  
  160.           INITDOORDRIVER(filen: string);                   [CTL]
  161.  
  162.               This procedure MUST be called before any of
  163.           DoorDriver's features are used. In fact, in most cases it
  164.           should be the first statement that your program executes.
  165.           The FILEN variable specifies the filename of the control
  166.           file that DoorDriver will use (i.e. DOORDRIV.CTL).
  167.               InitDoorDriver does a variety of things including
  168.           loading and processing the control file, reading the drop
  169.           files, setting up serial I/O. It also sets up an "EXIT
  170.           Procuedure" which will automatically close down the serial
  171.           I/O when your program is finished.
  172.  
  173.           DISPLAYFILE(Filen: String);                      [OUT]
  174.  
  175.                This Procedure is usefull in that it will transfer an
  176.           Ascii or Ansi file, and will put "(C)ontinue, (S)top,
  177.           (N)onstop" to stop an Ascii file from scrolling of the
  178.           page and thus allowing the user to read this file at his
  179.           or her own speed.
  180.  
  181.  
  182.           DISPLAY_MACRO(s: string);                        [OUT]
  183.  
  184.                This procedure is used to display a macro-string. The
  185.           macro string is usually contained in the variable
  186.           MACRO_STRING.
  187.  
  188.  
  189.           PROMPT(var s: string; length: integer; hi: boolean); [INP]
  190.  
  191.                The prompt procedure is a high-level string input
  192.           routine. It allows you to specify the maximum length of
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.           DoorDriver Door Kit                      By Scott M. Baker
  200.  
  201.  
  202.  
  203.  
  204.  
  205.           the input string and if HI is set to true, it will hilight
  206.           the input in reverse background. The colors for the prompt
  207.           routine are defined in the control file.
  208.  
  209.  
  210.           RECORD_MACRO(var s: string);                     [INP]
  211.  
  212.                This procedure allows the user to record a macro
  213.           string, up to 255 characters that will be invoked whenever
  214.           the CTRL-N key is pressed. The macro is stored in the
  215.           string variable S. To activate the macro capability, you
  216.           must place the macro into the string variable
  217.           "MACRO_STRING".
  218.  
  219.  
  220.           SCLRSCR;    { ANSI code }                        [OUT]
  221.  
  222.                This procedure clears the remote side's and the local
  223.           side's screen.
  224.  
  225.           SCRLEOL;                                         [OUT]
  226.  
  227.                This procedure will clear up to then end of the
  228.           current line. (note: only works when caller has ANSI
  229.           capabilities)
  230.  
  231.  
  232.           SET_FOREGROUND(b: byte); {chg SRL to byte }      [OUT]
  233.  
  234.                The set_foreground procedure sets the current
  235.           foreground color to the one specified by the byte
  236.           variable, b. The color is set both on the local side and
  237.           the remote side if the remote user has ANSI toggled on.
  238.           The acceptable range for the color is 0-31. Colors 0-15
  239.           are standard foreground colors and 16-31 represent colors
  240.           0-15 but in blinking mode.
  241.  
  242.           SET_COLOR(f,b: byte);  {by S. Lorenz }        [OUT]
  243.  
  244.                The set_color procedure sets the current foreground
  245.           color and background and are specified by the variable
  246.           bytes f and b. The color is set both on the local side and
  247.           the remote terminal if the remote user has toggled his
  248.           ANSI on. The acceptable range for the f is 0-31 and b is
  249.           0-7.
  250.  
  251.           SET_BACKGROUND(b: byte);  {chg SRL to byte }     [OUT]
  252.  
  253.                The set_background procedure sets the current
  254.           background color to the one specified by the byte
  255.           variable, b. The color is set both on the local side and
  256.           the remote terminal if the remote user has toggled his
  257.           ANSI on. The acceptable range for the color is 0-7.
  258.  
  259.  
  260.           SGOTO_XY(x,y: integer);                          [OUT]
  261.  
  262.                Sgoto_xy allows you to position the cursor on the
  263.           local and remote screen. The valid range for X is 1 to 80
  264.           and the valid range for Y is 1 to 24.
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.           DoorDriver Door Kit                      By Scott M. Baker
  273.  
  274.  
  275.  
  276.  
  277.  
  278.           SREAD_CHAR(var c: char);                         [INP]
  279.  
  280.                This procedure waits for a character to be pressed
  281.           and then returns that character in the character variable.
  282.           No echoing is performed (i.e. the user will not see the
  283.           key he pressed). If you wish echoing, you must again write
  284.           the character with SWRITE below. This routine is useful
  285.           for writing your own lowlevel readln routines or
  286.           performing "hot-key" operations. It is a direct
  287.           replacement for CH:=READKEY.
  288.  
  289.           SREAD(var s: string);                            [INP]
  290.  
  291.                The sread procedure accomplishes the equivilant of
  292.           the Turbo Pascal procedure READLN. A string is read from
  293.           the user and wher the CR character is obtained, the
  294.           procedure exits with the string stored in the string
  295.           variable, s.
  296.  
  297.  
  298.           SREAD_NUM(var i: integer);                       [INP]
  299.  
  300.                The sread_num procedure is almost identical to the
  301.           sread procedure except it will read an integer variable
  302.           instead of a string. Only the characters 0-9 are allowed
  303.           to be entered by the user. The value returned will be in
  304.           the range of -32768 to +32768.
  305.  
  306.  
  307.           SREAD_NUM_BYTE(var b: byte);                     [INP]
  308.  
  309.                The sread_num_byte procedure is almost identical to
  310.           the sread procedure except it will read an byte variable
  311.           instead of a string. Only the characters 0-9 are allowed
  312.           to be entered by the user. The value returned will be in
  313.           the range of 0 to 255.
  314.  
  315.  
  316.           SREAD_NUM_WORD(var w: word);                     [INP]
  317.  
  318.                The sread_num_word procedure is almost identical to
  319.           the sread procedure except it will read an word variable
  320.           instead of a string. Only the characters 0-9 are allowed
  321.           to be entered by the user. The value returned will be in
  322.           the range of 0 to 65535.
  323.  
  324.  
  325.           SREAD_NUM_LONGINT(var l: longint);               [INP]
  326.  
  327.                The sread_num_longint procedure is almost identical
  328.           to the sread procedure except it will read an longint
  329.           variable instead of a string. Only the characters 0-9 are
  330.           allowed to be entered by the user. The value returned will
  331.           be in the range of -2147483648 to +2147483647.
  332.  
  333.  
  334.  
  335.  
  336.  
  337.           DoorDriver Door Kit                      By Scott M. Baker
  338.  
  339.  
  340.  
  341.  
  342.  
  343.           SWRITE(s: string);                               [OUT]
  344.  
  345.                The swrite procedure is the equivilant of the Turbo
  346.           Pascal WRITE procedure. Swrite will simultaniously write
  347.           to both the local screen and the remote terminal. No CR/LF
  348.           sequence is added to the end of the string. (note: You may
  349.           also use WRITE(SOUTPUT,s))
  350.  
  351.  
  352.           SWRITELN(s: string);                             [OUT]
  353.  
  354.                The swriteln procedure is the equivilant of the Turbo
  355.           Pascal WRITELN procedure. Swrite will simultaniously write
  356.           to both the local screen and the remote terminal. A CR/LF
  357.           sequence is appended to the end of the string. (note: You
  358.           may also use WRITELN(SOUTPUT,s))
  359.  
  360.           DDASSIGNSOUTPUT(f: text);                        [CTL]
  361.  
  362.                This procedure assigns the simultanious output
  363.           channel to a text file. This is done automatically by
  364.           INITDOORDRIVER to SOUTPUT (i.e. DDASSIGNSOUTPUT(SOUTPUT).
  365.           But, if you wish to assign it to a different file, you may
  366.           do it with this procedure. For example:
  367.  
  368.           DDASSIGNSOUTPUT(my_output_file);
  369.           rewrite(my_output_file);
  370.           writeln(my_output_file,'This will go to both local and '+
  371.                                   'remote.');
  372.  
  373.  
  374.           Reference - Functions
  375.           ---------------------
  376.  
  377.           SKEYPRESSED: Boolean;                            [INF]
  378.  
  379.                SKEYPRESSED will return TRUE if a key has been
  380.           pressed and is waiting to be read and FALSE if no key has
  381.           been pressed. It is the equivelant of Turbo Pascal's
  382.           KEYPRESSED function.
  383.                This also allows the program to pause until the user
  384.           presses a key. When used in a loop like this it stops
  385.           everything until user input occurs.
  386.  
  387.                Repeat Until skeypressed;
  388.  
  389.  
  390.           TIME_LEFT: Byte;                                 [INF]
  391.  
  392.                The time_left function returns the amount of time
  393.           left in minutes. This time is computed automatically by
  394.           doordriver for you.
  395.  
  396.           Reference - Variables
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.           DoorDriver Door Kit                      By Scott M. Baker
  404.  
  405.  
  406.  
  407.  
  408.  
  409.           ---------------------
  410.  
  411.           SOUTPUT: text;                                   [OUT]
  412.  
  413.                This text file is associated with the simultanious
  414.           output channel. It provides an alternate form of IO than
  415.           using swrite/swriteln. To use, simply treat SOUTPUT as it
  416.           were a normal text file. For example,
  417.  
  418.             Writeln(SOUTPUT,'This is a test'); is the same as
  419.           swriteln('This is a test');
  420.  
  421.             When is this useful? When you want to use WRITELN's
  422.           ability to write various data types (i.e. integers, reals,
  423.           etc) or it's ability to format output. For example:
  424.  
  425.             USING SWRITELN: str(integer_data,tempstr);
  426.           swriteln(tempstr);
  427.  
  428.             USING SOUTPUT:  writeln(soutput,integer_data);
  429.  
  430.           ALTKEYS: (see configurable alt key section)
  431.  
  432.           ALTHELP: (see configurable alt key section)
  433.  
  434.           ANSION: boolean;                                 [CTL]
  435.  
  436.               This variable controls whether local output (it has
  437.           nothing to do with remote) will go directly to the local
  438.           screen or if it will be sent through doordriver's
  439.           emulation routine. Since the emulation routine is slow in
  440.           comparison to direct output, this variable is defaulted to
  441.           FALSE. If you want to send your own ANSI codes to the
  442.           screen through SWRITE/SWRITELN, then you will have to set
  443.           this variable to TRUE.
  444.  
  445.           BAUD_RATE: integer;                              [INF]
  446.  
  447.                This variable holds the user's current baud rate.
  448.  
  449.           BBS_SOFTWARE: byte;                              [INF]
  450.  
  451.               The following numbers indicate software names:
  452.  
  453.               0 : Maintenance mode               n/a
  454.               1 : Local-only operation           n/a
  455.               2 : Sysop-fast logon only          n/a
  456.               3 : Qbbs                           DORINFOx.DEF
  457.               4 : Pcboard-12                     PCBOARD.SYS
  458.               5 : WWIV                           CHAIN.TXT
  459.               6 : n/a                            n/a
  460.               7 : Rbbs 16.x                      DORINFOx.DEF
  461.               8 : Phoenix                        EXITINFO.DAT
  462.               9 : WildCat (pre - 3.0)            CALLINFO.BBS
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.           DoorDriver Door Kit                      By Scott M. Baker
  470.  
  471.  
  472.  
  473.  
  474.  
  475.               10: Pcboard-14                     PCBOARD.SYS
  476.               11: DOOR.SYS                       DOOR.SYS
  477.               12: Spitfire                       SFDOORS.DAT
  478.  
  479.  
  480.           BBS_TIME_LEFT: integer;                          [INF]
  481.  
  482.               This holds the amount of time that the user had left
  483.           when he entered the door. It is loaded from the DROP FILE
  484.           by INITDOORDRIVER. Note that this provides the time left
  485.           when the user ENTERED the door, not the current time left.
  486.           The current amount of time left is calculated by the
  487.           function TIME_LEFT.
  488.  
  489.           BOARD_NAME: String[70];                          [INF]
  490.  
  491.                Board_Name hold the current BBS's name that is set in
  492.           the control file.
  493.  
  494.           CHARORIGIN: CharOriginType;                      [INF]
  495.  
  496.                Returns either LocalChar or RemoteChar depending on
  497.           where the last sread_char was received from. This is
  498.           mainly used in the chat routine to set different
  499.           foreground colors for local and remote users.
  500.  
  501.           COM_PORT: byte;                                  [INF]
  502.  
  503.                Contains the current com port that serial output is
  504.           going to. Should be a zero if in local mode.
  505.  
  506.  
  507.           CURRENT_FORGROUND: byte;                         [INF]
  508.  
  509.                This variable stores the current foreground color.
  510.  
  511.  
  512.           CURRENT_BACKGROUND: byte;                        [INF]
  513.  
  514.                This variable stores the current background color.
  515.  
  516.           CURLINENUM: byte;                                [INF]
  517.  
  518.                This variable is used internally to control the more
  519.           prompt. It is incremented when a line of text is sent out.
  520.           When it reaches 24, a <more> is sent. This is of course,
  521.           providing that morechk:=true.
  522.  
  523.                                                            [INF]
  524.           GRAPHICS: byte;
  525.  
  526.               Graphics specifies a text mode:
  527.  
  528.               1 : Ascii - General Text
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.           DoorDriver Door Kit                      By Scott M. Baker
  536.  
  537.  
  538.  
  539.  
  540.  
  541.               2 : Ascii's Extended Graphics and General Text
  542.               3 : Ansi Color and Graphics
  543.               4 : Ansi Color and Graphics and Ansi Music (See
  544.                   Section on ANSI.TPU)
  545.  
  546.           LOCAL: boolean;                                  [INF]
  547.  
  548.               This boolean is alway true if in local mode and false
  549.           if in remote mode.
  550.  
  551.  
  552.           MINTIME: byte;                                   [INF]
  553.  
  554.                (check this - don't know)
  555.  
  556.           MORECHK: boolean;                                [CTL]
  557.  
  558.                This boolean allows you to toggle the more prompts on
  559.           or off. If TRUE, then doordriver will display a "more"
  560.           prompt every 24 lines.
  561.  
  562.  
  563.           NODE_NUM: byte;                                  [INF]
  564.  
  565.                Returns the current Node that the door is running
  566.           under. Defaulted to 1 in a single node system. This
  567.           corresponds directly to the "/Nx" command line parameter.
  568.  
  569.  
  570.           NOTIME: String;                                  [CTL]
  571.  
  572.                (check this)
  573.  
  574.                When the users time limit has been reached this
  575.           string will be displayed then the user will be returned to
  576.           the bbs. This string has a default of "(***TIME LIMIT
  577.           EXCEEDED***)".
  578.  
  579.           STACKED: string;                                 [---]
  580.  
  581.                The Procedure sread and sreadln can have stacked
  582.           commands which is when a user type something in like this:
  583.  
  584.                             "m;101;m;102;m;103;m;104"
  585.  
  586.                Notice the ";"'s throughout the example. well this is
  587.           a stacked command. the ";"'s indicate a seperate
  588.           operation. This allows the user to type in multiple
  589.           operations to preform on one line and not have to go
  590.           through each and every prompt of the door. This can be
  591.           very useful when used in combi- nation with the
  592.           Record_Macro command.
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.           DoorDriver Door Kit                      By Scott M. Baker
  602.  
  603.  
  604.  
  605.  
  606.  
  607.           STATFORE: byte;                                  [CTL]
  608.  
  609.                The status line foreground.
  610.  
  611.  
  612.           STATBACK: byte;                                  [CTL]
  613.  
  614.                The status line background.
  615.  
  616.  
  617.           STATLINE: boolean;                               [CTL]
  618.  
  619.                A status line pops while any door is in operation if
  620.           this boolean is set true. The status line contains the
  621.           user name and the program name an the users time left.
  622.  
  623.  
  624.           SYSOP_FIRST_NAME: string[30];                    [INF]
  625.  
  626.                Returns the first name of the sysop. The name is
  627.           entered into door-driver through the control file.
  628.  
  629.  
  630.           SYSOP_LAST_NAME: string[30];                     [INF]
  631.  
  632.                Returns the last name of the sysop. The name is
  633.           entered into door-driver through the control file.
  634.  
  635.  
  636.           USER_FIRST_NAME: string[30];                     [INF]
  637.  
  638.                Returns the first name of the current user of the
  639.           door program. The user's name is determined from whatever
  640.           door information is passed from the bbs software.
  641.  
  642.  
  643.           USER_LAST_NAME: string[30];                      [INF]
  644.  
  645.                Returns the last name of the current user of the door
  646.           program. The user's name is determined from whatever door
  647.           information is passed from the bbs software.
  648.  
  649.  
  650.           USER_ACCESS_LEVEL: word;                         [INF]
  651.  
  652.                Returns the access level of the user. The user's
  653.           access level is determined from whatever door information
  654.           is passed from the bbs software.
  655.  
  656.  
  657.           PROGNAME: String[60];                            [CTL]
  658.  
  659.                This option must be set by the programmer, preferably
  660.           in the beginning of the door. It sets the name that will
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.           DoorDriver Door Kit                      By Scott M. Baker
  668.  
  669.  
  670.  
  671.  
  672.  
  673.           be displayed centered on line 25 of the screen. It is
  674.           simply used for cosmetic purposes.
  675.  
  676.  
  677.           MACRO_STRING: string;                            [INF/CTL]
  678.  
  679.                 The contents of this variable are treated as a
  680.           macro. Whenever the user types a CTRL-N, the string will
  681.           be output. The string may be easily recorded with the
  682.           RECORD_MACRO procedure and displayed with the
  683.           DISPLAY_MACRO procedure.
  684.  
  685.  
  686.           SETFORECHECK: boolean; (default=FALSE)           [CTL]
  687.  
  688.                 This variable when set to TRUE will cause DOORDRIV
  689.           to filter out repetetive SET_FOREGROUND() calls. If for
  690.           example, you set the foreground to gray, then set it to
  691.           gray again later while the foreground is still gray, the
  692.           second call would be ignored. This can spare the user from
  693.           the slowdown effects of meaningless, repetetive
  694.           SET_FOREGROUND calls.
  695.  
  696.           Referance - Constants
  697.           ---------------------
  698.           VERSION = 'Version 5.00; 9-18-91'        (LARGE VERSION)
  699.                   = 'Version 5.00S; 9-18-91'       (SMALL VERSION)
  700.  
  701.  
  702.           Reference - Procedure Substitutions
  703.           -----------------------------------
  704.           This section is provided to help you in figuring out which
  705.           doordriver routines you should call to replace turbo's
  706.           standard I/O routines.
  707.  
  708.           READKEY:
  709.  
  710.               Readkey is used in many normal programs to get a
  711.           single character. (i.e. CHAR:=readey). This can be
  712.           replaced by SREAD_CHAR(char);.
  713.  
  714.           WRITELN(xxxx);  (or WRITE(xxxx))
  715.  
  716.               The writeln procedure is probably the most common and
  717.           numerous change that you will have to make. DoorDriver
  718.           provides the SWRITE/SWRITELN procedures to do the job of
  719.           turbo's write/writeln. In addition, the SOUTPUT file is
  720.           also available. Let's take a look at some examples:
  721.  
  722.           Ex 1
  723.           ----
  724.            Convert "writeln('Scott was here!');"
  725.  
  726.               --> swriteln('Scott was here!');
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.           DoorDriver Door Kit                      By Scott M. Baker
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.            or --> writeln(soutput,'Scott was here!');
  741.  
  742.           Ex 2
  743.           ----
  744.            int is an integer.
  745.            Convert "write(int);"
  746.  
  747.               --> str(int,tempstr); swrite(tempstr);
  748.  
  749.            or --> write(soutput,int);
  750.  
  751.           Ex 3
  752.           ----
  753.            r is a real.
  754.            Covert "writeln(r:2:2);"
  755.  
  756.               ---> str(r:2:2,tempstr); swriteln(tempstr);
  757.  
  758.            or ---> writeln(soutput,r:2:2);
  759.  
  760.               As you can see, the SWRITE/SWRITELN method is easier
  761.           if you are using string type data, but the
  762.           write(SOUTPUT,xxx) method is better for numerical types.
  763.           You can use whichever you like.
  764.  
  765.  
  766.           CLREOL:
  767.  
  768.               You can replace CLREOL with SCLREOL, but please note
  769.           that it will only work when the caller has ANSI
  770.           capabilities. If the caller doesn't have ansi, then he'll
  771.           get a load of garbage.
  772.  
  773.  
  774.           CLRSCR:
  775.  
  776.               CLRSCR can be directly converted to SCLRSCR. This
  777.           works for either ANSI or non-ANSI users.
  778.  
  779.           GOTOXY(x,y):
  780.  
  781.               GOTOXY(x,y) can be converted into SGOTO_XY(x,y), but
  782.           again, this will only work for ansi users.
  783.  
  784.           READLN(string_variable) ---> SREAD(string_variable)
  785.  
  786.           READLN(integer_variable) ---> SREAD_NUM(integer_variable)
  787.  
  788.           READLN(word_variable) ---> SREAD_WORD(word_variable)
  789.  
  790.           READLN(long_variable) ---> SREAD_LONGINT(long_variable)
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.           DoorDriver Door Kit                      By Scott M. Baker
  800.  
  801.  
  802.  
  803.  
  804.  
  805.           REFERENCE - Units
  806.           -----------------
  807.  
  808.               I'll briefly list the included units and what they do
  809.           here. Inside UNITINTR.ARJ you will find the interface
  810.           section of all of DoorDriver's units. Some are commented
  811.           and come are not.
  812.  
  813.               *DOORDRIV.TPU
  814.  
  815.                This is the "large" version of doordriver. It's the
  816.           main unit that you need to use.
  817.  
  818.               *DDANSI.TPU
  819.  
  820.                Contains procedures used by doordriver to display
  821.           ANSI on local screen.
  822.  
  823.               *DDFOSSIL.TPU
  824.  
  825.                Contains procedures used by doordriver to interact
  826.           with fossil drivers.
  827.  
  828.               *DDSCOTT.TPU
  829.  
  830.                Miscellanious procedures used by doordriver.
  831.  
  832.               *REWINDOW.TPU
  833.  
  834.                The remote window routines.
  835.  
  836.               *CFGEDITR.TPU
  837.  
  838.                Configurable editor.
  839.  
  840.               *COMIO.TPU
  841.  
  842.                Medium-level COM I/O used by doordriver.
  843.  
  844.               *ASYNC.TPU/SZASYNC.OBJ
  845.  
  846.                Internal COM routines.
  847.  
  848.               *DDOVR.TPU
  849.  
  850.                Overlayable unit containing code that gets
  851.           information out of bbs drop files (i.e. DORINFOx.DEF, etc)
  852.  
  853.               *DDOVR2.TPU
  854.  
  855.                Overlayable unit that contains code to process
  856.           control file.
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.           DoorDriver Door Kit                      By Scott M. Baker
  866.  
  867.  
  868.  
  869.  
  870.  
  871.           REFERENCE - CONFIGURABLE ALT KEYS
  872.           ---------------------------------
  873.               Inside doordriver's SREAD_CH routine (which handles
  874.           all input from the user), doordriver processes ALT-KEY
  875.           combinatations (such as ALT-H, ALT-D, etc). These ALT-KEYs
  876.           activate certain features within doordriver.
  877.               Doordriver includes support to "hook" your own
  878.           procedures into a certain ALT key. when the sysop hits
  879.           that key, whatever procedure you define will be executed.
  880.               DoorDriver defines the variable ALTKEYS as an
  881.           array['A'..'Z'] of pointer. These correspond to ALT-A
  882.           through ALT-Z. To link a procedure into these alt keys,
  883.           you must do the following:
  884.  
  885.               1: Your procedure must be compiled FAR. (i.e. put
  886.                  {$F+} and {$F-} around it)
  887.  
  888.               2: Your procedure must not have any parameters passed
  889.                  to it.
  890.  
  891.               3: You must set the appropriate pointer in ALTKEYS to
  892.                  point to your procedure.
  893.  
  894.               For example:
  895.  
  896.           {$F+}
  897.           PROCEDURE Display_Neato_message;
  898.           begin;
  899.            swriteln('Neat-o! The Alt Keys worked!');
  900.           end;
  901.           {$F-}
  902.  
  903.           PROCEDURE Install_Neato;
  904.           begin;
  905.            ALTKEYS['N']:=@Display_Neato_message; {Hook in the proc}
  906.            new(althelp['N']);                    {create a help
  907.                                                   line}
  908.            althelp^['N']:='Neato!';              {Put in help}
  909.           end;
  910.  
  911.               The procedure INSTALL_NEATO is what installs the
  912.           Display_Neato_Message procedure into the ALT-N key. It
  913.           also does a few other things which may need a little
  914.           explanation:
  915.               The ALTHELP array is an array of ^STRING which
  916.           contains strings which will be displayed in doordrivers
  917.           hot-key help (ALT-H). To create a help string, you have to
  918.           NEW the string, then put the data in. This is not
  919.           absolutely necessary and is only used for cosmetic
  920.           purposes.
  921.               Note: You can also use ALTKEYS to disable or override
  922.           the built in ALT-C (chat), ALT-H (help), and ALT-D (drop
  923.           to dos). For example, ALTKEYS['D']:=Nil would disable drop
  924.           to dos.
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.           DoorDriver Door Kit                      By Scott M. Baker
  932.  
  933.  
  934.  
  935.  
  936.  
  937.               Now, if you aren't totally confused, I'm real
  938.           surprised.... (grin). The sample program, EDITDEMO sets up
  939.           a configurable editor screen tied to ALT-E.
  940.  
  941.           REFERENCE - ANSI MENU ROUTINES
  942.           ------------------------------
  943.  
  944.                There is an additional TPU file included with the
  945.           doordriver package that includes a user-friendly ANSI-MENU
  946.           handler. The TPU can be called up with the statement "USES
  947.           ANSIMENU". The menu system is accessed by the single
  948.           function:
  949.  
  950.                    CHAR:=GetAnsiMenu(menu_definition_template)
  951.  
  952.                 The menu-definition-template type is declared within
  953.           the unit. It is identical to the structure below:
  954.  
  955.  
  956.                  menutype = record
  957.                              header: string[80];
  958.                              footer: string[80];
  959.                              headercolor,
  960.                              footercolor,
  961.                              optioncolor,
  962.                              desccolor,
  963.                              arrowcolor,
  964.                              bracketcolor: byte;
  965.                              numoptions: byte;
  966.                              options: array[1..20] of string[1];
  967.                              desc: array[1..20] of string[80];
  968.                             end;
  969.  
  970.                 The structure is usually defined by your program as
  971.           a constant. The ANSIMENU procedure interprets this
  972.           strucure and uses it to generate a centered menu. The menu
  973.           options may be selected by using the numeric keypad (the 8
  974.           for up and the 2 for down) or by simply typing the the
  975.           letter of the option. A sample door, NEWS.PAS, is included
  976.           to demonstrate the use of the ansimenu unit.
  977.  
  978.           REFERENCE - DDTERM TERMINAL SUPPORT
  979.           -----------------------------------
  980.           DDTERM support killed! It just didn't accomplish a whole
  981.           lot, so I nuked the support. Sorry if anyone was using it,
  982.           but DDTerm never really has amounted to much over here.
  983.  
  984.  
  985.           REFERENCE - SAMPLE DOORS
  986.           ------------------------
  987.  
  988.               I have included two sample door programs, NEWS.PAS and
  989.           BBSLIST.PAS. These two programs are intended to be an
  990.           example of how doordriver can be used.
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.           DoorDriver Door Kit                      By Scott M. Baker
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.               NEWS.PAS is a program that I once wrote as an online
  1004.           news reader for USA Today, Movie Review, and a few other
  1005.           electronic magazine services. It's a good demonstration of
  1006.           how to use the ANSIMENU unit, displayfile, and several of
  1007.           DoorDriver's features.
  1008.               BBSLIST.PAS is a bbs list maintainer that I wrote a
  1009.           while back. Like NEWS, it's a good example of the ANSIMENU
  1010.           unit.
  1011.               You are free to use code in these programs if you
  1012.           like, but I do maintain a copyright on those programs. If
  1013.           you do use code, I expect to be "cut in" to whatever
  1014.           extent the code was used. For example, if you developed
  1015.           BBSLIST.PAS into a little more powerful program and
  1016.           started distributing it, I would expect a reasonable
  1017.           portion of whatever profits you make.
  1018.  
  1019.           REFERENCE - IMPORTANT THINGS
  1020.           ----------------------------
  1021.  
  1022.           -> What happens when the user runs out of time, sleep
  1023.           -> disconnects, or drops carrier?
  1024.  
  1025.           Doordriver will HALT. This will cause an immediate
  1026.           termination of the door. If your door needs to save any
  1027.           data then you should use an EXIT PROCEDURE to save the
  1028.           data. For example:
  1029.  
  1030.           {$F+} procedure myexit; {$F-}
  1031.           begin;
  1032.            save_our_data;
  1033.            exitproc:=exitsave;
  1034.           end;
  1035.  
  1036.           {main program}
  1037.           begin;
  1038.            InitDoorDriver......
  1039.            ExitSave:=Exitproc;
  1040.            ExitProc:=@myexit;
  1041.            .......
  1042.           end.
  1043.  
  1044.           This will setup MYEXIT so it is run whenever your program
  1045.           exits for any reason. This is the best way to trapped
  1046.           carrier dropped, out of time, etc.
  1047.  
  1048.           NOTE #1: The carrier, time left, and sleep disconnect are
  1049.           only tested when doordriver is waiting for a keypress
  1050.           (i.e. sread_char, sread, etc)
  1051.  
  1052.           NOTE #2: If checktime=false then DoorDriver will not check
  1053.           to see if the user is out of time.
  1054.  
  1055.           -> How do I use ANSI in my programs?
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.           DoorDriver Door Kit                      By Scott M. Baker
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.           You can use ANSI by two methods:
  1070.  
  1071.            1) By using the set_foreground, set_background, and
  1072.               sclrscr procedures, you can perform some basic ANSI
  1073.               functions. DoorDriver will automatically enable these
  1074.               fucntions when ANSI is available and disable it when
  1075.               not.
  1076.  
  1077.            2) If you set ANSION:=TRUE, then you can just SWRITE your
  1078.               ansi sequences directly to the screen. When you turn
  1079.               ANSION on, it will slow down screen writes, so it is
  1080.               advisable to do it only when necessary.
  1081.  
  1082.           REFERENCE - CARRIER DETECT
  1083.           --------------------------
  1084.               I am currently writing a door tutorial for Michael
  1085.           Crosson's Carrier Detect Journal. Carrier Detect is a
  1086.           bi-monthly electronic journal produced by Mike and it is
  1087.           quite good.
  1088.               The Door Tutorial that I am writing was started in the
  1089.           September 1991 issue of CD and will continue as long as
  1090.           possible. I have included the september extract of Door
  1091.           Tutorial as DDTUT1.DOC.
  1092.               Issues of Carrier Detect can be found on my bbs.
  1093.  
  1094.  
  1095.           UPDATE HISTORY
  1096.           --------------
  1097.  
  1098.                   Version 2.50:
  1099.  
  1100.            - First Public release
  1101.  
  1102.                   Version 2.55:
  1103.  
  1104.           - DoorDriver screen removed and replaced by a 2-line
  1105.           message.
  1106.  
  1107.           - Small problem with SET_FOREGROUND has been fixed.
  1108.  
  1109.           - The NEWS.DIR file which was left out in previous
  1110.           versions has now been included.
  1111.  
  1112.                   Version 2.60:
  1113.  
  1114.           - Modifications to the ANSIMENU TPU 1) The TPU is now
  1115.           called "ANSIMENU" instead of "ANSIMENUSYSTEM". If your
  1116.           program was using the ansimenu routines, then the "uses"
  1117.           statement must be changed from "uses ansimenusystem" to
  1118.           "uses ansimenu". 2) The function name "ANSIMENU" has been
  1119.           repleaced by "GETANSIMENU". All occurences of the function
  1120.           call <char>:=Ansimenu(<MenuTemplate>) must be changed to
  1121.           <char>:=GetAnsiMenu(<MenuTemplate>).
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.           DoorDriver Door Kit                      By Scott M. Baker
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.           - DoorDriver title screen/info shrunk even more at users'
  1136.           request.
  1137.  
  1138.                   Version 3.00
  1139.  
  1140.           - Doordriver majorly modified to switch to use of control
  1141.           file rather than the /C configuration.
  1142.  
  1143.           - INITDOORDRIVER(filename) must be called before any of
  1144.           doordrivers routines are used.
  1145.  
  1146.           - SREAD_CHAR was omitted by accident in previous versions
  1147.           of the documentation.
  1148.  
  1149.           - Many new configuration options present in the control
  1150.           file including EGA/VGA support.
  1151.  
  1152.           - Two versions of DoorDriver are now included. DOORDRIV is
  1153.           the normal version with all features included while
  1154.           DOORDRSM is the SMALL version which leaves out the
  1155.           REWINDOW, ALT-KEY, and SYSOP FILTER support. If your
  1156.           program begins to run low on memory, you may wish to
  1157.           consider using DOORDRSM instead of DOORDRIV.
  1158.  
  1159.           - Doordirv.INT has been included in the package and
  1160.           includes the actual interface section of doordriver.
  1161.  
  1162.           - CFGEDITR.TPU has been altered. (See edittest.pas for the
  1163.           new template record structure)
  1164.  
  1165.                   Version 4.00
  1166.  
  1167.           - The DDANSI unit went through a major overhaul - it
  1168.           should now be faster and more error free.
  1169.  
  1170.           - DDTERM support included - see the above section for
  1171.           information.
  1172.  
  1173.           - Both TP5.5 and TP6.0 routines included.
  1174.  
  1175.                   Version 5.00
  1176.  
  1177.           - The actual bbs-information loading code has been moved
  1178.           into DDOVR.TPU. This file may be overlaid if you wish to
  1179.           conserve memory.
  1180.  
  1181.           - Control file processing code moved to DDOVR2.TPU.
  1182.  
  1183.           - SOUTPUT file and DDAssignSOutput(f:text) procedure
  1184.           added.
  1185.  
  1186.           - Added spitfire and Door.sys support.
  1187.  
  1188.           - Removed DDTERM support.
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.           DoorDriver Door Kit                      By Scott M. Baker
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.           - Changed around the way the configurable ALT-Keys worked.
  1203.           If you were using the old method, please see the above
  1204.           section on configurable alt keys.
  1205.  
  1206.           - Removed the REWindow support routines. They weren't
  1207.           widely used.
  1208.  
  1209.           - Documentation upgraded a lot!
  1210.  
  1211.           Credits
  1212.           -------
  1213.           SCOTT BAKER (myself)
  1214.  
  1215.               Author of DOORDRIVER, NEWS, and ANSIMENU.
  1216.  
  1217.           DERRICK PARKHURST
  1218.  
  1219.               Repairs to the still malfunctioning ANSI.TPU unit.
  1220.               Various work on configurable editor routines.
  1221.               Remote windowing and Windowed chat support.
  1222.               Sysop filter.
  1223.  
  1224.           CARL EVANS (of Vervans War Board)
  1225.  
  1226.               Addition of PC-BOARD 14 support.
  1227.  
  1228.  
  1229.           Copyright
  1230.           ---------
  1231.  
  1232.                  The DOORDRIVER routines are copyrighted by Scott
  1233.           Baker and Derrick Parkhurst. This copyright includes all
  1234.           material contained in this package - TPU modules, PAS
  1235.           files, sample door, Documentation, etc. You are permitted
  1236.           to USE these routines in your own doors if you wish under
  1237.           the following conditions:
  1238.  
  1239.                      1) Any material which you use from this package
  1240.           must not be modified in any way. You can use it, but you
  1241.           can't hack into it.
  1242.  
  1243.                      2) If you intend to use this kit for commercial
  1244.           purposed (this includes SHAREWARE), then you must register
  1245.           it with the author and pay the required minimum
  1246.           registration fee.
  1247.  
  1248.                      3) You MUST include credit to the authors of
  1249.           these routines in your program, documentation, etc.
  1250.  
  1251.           Suggested Registration Fee
  1252.           --------------------------
  1253.               I encourage you to send me whatever you feel
  1254.           doordriver is worth. The minimum that I will consider is
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.           DoorDriver Door Kit                      By Scott M. Baker
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.           $25 which I feel doordriver is easily worth that much.
  1268.               However, don't feel you are limited to $25. You can
  1269.           send as much as you like. If doordriver is a major part of
  1270.           your program which you could not do without it, then
  1271.           please compensate me for my work. For example, I have a
  1272.           few authors who are sending me a percentage of their
  1273.           profit off their doors as compensation.
  1274.  
  1275.               I encourage you to register this package with the
  1276.           authors if you find it useful to your programming.
  1277.           Registration/donations can be mailed to the following
  1278.           address:
  1279.  
  1280.           Scott M. Baker
  1281.           6431 Tierra Catalina #48
  1282.           Tucson, Az 85718
  1283.  
  1284.                  If you wish to contact the authors of this software
  1285.           for any reason, they may be reached by the address above,
  1286.           or you may log on to our software support bbs:
  1287.  
  1288.           "The Not-Yet-Named bbs"
  1289.  
  1290.           Sysop: Scott Baker
  1291.           NODE #1: (602) 577-3650 1200-9600  (V.32)     1:300/9
  1292.           NODE #2: (602) 577-3419 2400-14400 (USR DUAL) 1:300/29
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.